home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 1 (Walnut Creek)
/
Aminet - June 1993 [Walnut Creek].iso
/
aminet
/
misc
/
sci
/
dproc126.lha
/
docs
/
DataProc.hlp
< prev
next >
Wrap
Text File
|
1993-02-28
|
113KB
|
2,711 lines
1 dataproc
DataProc is a command-driven data processing program, which works much
like a tabular calculation program. DataProc reads in a command file
holding commands and data and can produce a number of different output
files for further processing with other software. DataProc is especially
designed to work with GNUPLOT and LaTeX. Both of the latter are available
as public domain software on almost any computer system.
Beyond the standard mathematics to apply on data several statistic specials
like regression and averaging are implemented.
You should pass a filename to DataProc. This file wil be read and executed
by DataProc. The default extension for this file is '.tst'. So DataProc
tries to open <filename.tst> if <filename> is not available. E.g.:
DataProc project.tst
DataProc project
are equivalent, unless a file named 'project' exists, which will then be
read by the second line. If the file 'project.tst' does not exist an error
will be issued.
If you don't pass a commandfilename, DataProc will enter the interactive
mode. Anything you enter behind the prompt will be executed just like
a commandfile line. As comments don't seem to make sense in interactive
mode, any comments will be interpreted as include file names. See
`commands include` for more information. An example session might be:
TeX:physics> DataProc
DataProc 1.221 (24.1.93)
© 1992 by MGR, Asgard
This Amiga copy is registered to Lars Hanke #: 000012
1 > *project1
[messages from execution of project1.tst]
2 > *project2
[messages from execution of project2.tst]
3 > #quit
TeX:physics>
2 politics
Some words about software in general. Never use original files to run
software. Always create copies and run them, because you will never
know what might happen to the software.
If you have problems getting started with the evaluation copy, contact
me immediately, no matter if you want this program or not. I cannot
test the software on a lot of systems with different configurations
and it may do really weired things on other systems. If I do not come
to know it, this won't change ever and at most leads to a bad reputation
of the program.
3 distribution
In a nutshell, DataProc may be distributed freely as long as
the following restrictions are met:
The distributor may only charge a fee up to the costs of
obtaining a public domain diskette from Fred Fish. The
distributor agrees to cease distributing the programs and data
involved if requested to do so by the author. The distributor
may only distribute an unmodified copy of the original program,
with all the supplied documentation and copyright notices
intact.
For more details, see the section called `License`.
3 support
If you have any suggestions, bug reports etc., feel free to
contact the author of DataProc at the address given in the
section "Registration". Additionally, you can reach me at:
Lars Hanke
FIDO: 2:245/5802.22
UUCP: mgr@asgard.bo.open.de
3 license
1. This license applies to the product called "DataProc", a
program available for the Amiga computer and MS-DOS (tm) machines,
published by Lars Hanke under the concepts of ShareWare, and
the accompanying documentation, example files and anything else
that comes with the original distribution. The terms "Programs"
and "DataProc" below, refer to this product. The license is
addressed as "you".
2. You may copy and distribute verbatim copies of the
programs' executable code and documentation as you receive it,
in any medium, provided that you conspicuously and appropriately
publish only the original, unmodified programs, with all
copyright notices and disclaimers of warranty intact and
including all the accompanying documentation, example files and
anything else that came with the original.
3. You may not copy and/or distribute these programs without
the accompanying documentation and other additional files that
came with the original. You may not copy and/or distribute
modified versions of these programs.
4. You may not copy, modify, sublicense, distribute or
transfer the programs except as expressly provided under this
license. Any attempt otherwise to copy, modify, sublicense,
distribute or transfer the programs is void, and will
automatically terminate your rights to use the programs under
this license.
5. By copying, distributing and/or using the programs you
indicate your acceptance of this license to do so, and all its
terms and conditions.
6. Each time you redistribute the programs, the recipient
automatically receives a license from the original licensor to
copy, distribute and/or use the programs subject to these terms
and conditions. You may not impose any further restrictions on
the recipients' exercise of the rights granted herein.
7. You may not disassemble, decompile, re-source or otherwise
reverse engineer the programs.
8. You may use the programs for a period of up to 40 days for
evaluation. After that, you have to register.
9. If you wish to incorporate parts of the programs into other
programs, write to the author to ask for permission.
10. You agree to cease distributing the programs and data
involved if requested to do so by the author.
11. You may charge a fee to recover distribution costs. The
fee for diskette distribution may not be more than the cost to
obtain a public domain diskette from Fred Fish.
3 warranty
THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED
BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS
IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS
WITH YOU. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE
COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.
3 disclaimer
No warranty, either express or implied, is made with respect
to the fitness or merchantability of DataProc.
Lars Hanke (referred to as "the author"), reserves the right to not
develop any future versions of DataProc.
The author will try to make a good faith attempt at
correcting any problems if any are discovered, but is in no way
required, nor bound to correct them.
The author neither assumes nor accepts any responsibility for
the use or misuse of these programs. He also will not be held
liable for damages or any compensation beyond the original
registration fee due to loss of profit or any other damages
arising out of the use, or inability to use these programs.
Lars Hanke will not be liable for any damage arising from the failure
of these programs to perform as described, or any destruction of other
programs or data residing on a system attempting to run the programs.
This does not depend on my knowledge of damaging errors in the programs.
I may change prices and distribution conditions at will, with every new
revision of the programs. I cannot be forced to distribute old revisions.
Registrations not meeting the current conditions will lead me to inform
you of the changes. You may then cancel your registration or meet the
new conditions. Note that you have to express any interest in special
distribution conditions explicitly, or I will assume that you agree with
the current conditions. Lars Hanke is not liable for any costs of monetary
transfers and other expenses concerning a cancelled registration.
3 registration
As already mentioned, this program is Shareware. Shareware is neither
Public Domain, nor Freeware, nor Giftware, nor Copyleft. If you decide
to use this program, you must pay for it! If you don't pay, but use, this
is software piracy, with all its legal consequences.
Some reasons to register: First of all, to stay legal, but as nobody cares
nowadays, there are some other good reasons. An important reason is the
support of the shareware idea. You don't buy shareware blindly, but you
may test it thoroughly before. But if nobody pays, it is only a logical
consequence that no-one will write shareware anymore and finally you have
no chance, but buying software blindly. Finally the support of Shareware
programmers will encourage them to care for their programs and you are
more likely to get the same support as with commercial software.
Unfortunately, experience tells us that those reasons aren't too convincing
for a lot of users. Well, here are some reasons to register DataProc.
First of all, the banner message will change from "unregistered" to your
name and registration number. Then you will be able to install DataProc
anywhere in your path, the evaluation copy may only be started form its
own location directory. Finally those nerve-racking Shareware posters
with its requests for keyboard input during the execution of your commandfile
will disappear. The evaluation copy of DataProc is fully operative, but
has limitations to the possibilities of automatic execution e.g. during
batch jobs and to a proper installation in your system, e.g. paths or
packing of the program. Due to a loss of dumb checks whether the copy may
be used or not, the registered software improves a great deal in performance,
especially the reloading of the own code in bytes will drop.
Remember, a software worth using is a software worth buying. And don't tell
me you can't afford DM 25.--, you could still sell your computer! This
price is for registration only. The keyfile will be sent via UseNet. If
you don't want your keyfile via UseNet or would like an update included
add DM 2.-- for European Union countries or DM 5.-- for countries outside
the EU, and I will send a disk including your keyfile and the most recent
DataProc version. Note: If the service "keyfile via email" becomes too
excessive, I may quit that service at will, either mine or the will of
my mailservers.
Send your registration (including: Name and address, DataProc version,
source you got DataProc from, your system configuration and your EMAIL
address) to:
MGR, Asgard
Lars Hanke
Schlachthofstr. 67
D-4690 Herne 2
FIDO: 2:245/5802.22
UUCP: mgr@asgard.bo.open.de
This is also the adress to send suggestions and bug reports to. For urgent
bug reports try:
bugs@asgard.bo.open.de
If you intend to install this programm on a multi user system, or are
interested in ports to other machines or want to customize it, send me a
note. I will gladly cooperate.
3 credits
Thanks to the developers of GNU-Plot and TeX. The existance of those
products was the main influence to start this project. Also the basic
layout of the user interface was drawn from there. This does of course
in no way apply to any code used for DataProc.
Thanks to TrapLand, showing me that SHAREWARE might work even in Europe.
I hope you don't mind that I took your legal stuff as the basis of the
DataProc license.
Thanks to Mr. Teulings, Mr. Preuß for beta testing and Mr. Kulka for
alpha testing. Thanks as well to Mr. Böllmann and Mr. Beisemann for
lending me their machines for the MS-DOS compilation.
Thanks to Mr. Teulings for "WRITE" coping with those goddamned space
syntax in the .doc file.
Thanks to all those helpful guys round FIDO and UseNet, helping me
with coding and porting problems.
Thanks to Commodore for producing the Amiga and to SAS for their
prompt help and support of their compiler.
Finally thanks to me for not needing any sleep at all and to my dog
for generously freeing me of that task, sleeping for both of us.
Thanks to Odin, the Aesir and the Runes for my name and logo.
2 basics
3 syntax
There are some basic rules about the structure of command files. In general
empty lines and the number of spaces are ignored. The same is with leading
and trailing spaces, tabs or whatsoever. DataProc does not distinguish
between different spacing characters.
The characters '*', ';' and '%' mark a commentline, which is ignored. Inline
comments are not yet supported. Note that in interactive mode the line
following the comment sign will be passed as arguments to the include
command. See `commands include` for more information.
The characters '!' and '$' will post whatever they are followed in that line
on screen during the execution of the commandfile. They should be used to
supervise proper operation of a commandfile.
A commandline is made up by ASCII characters and ends with the EOL character
(usu. $0a). By now you cannot mark a line as a follower.
Commandlines are made up by tokens. Each token is seperated by either a space
or ':', '/' or '&'. While '//' declares an empty token two spaces do not.
(See above). Since Version 1.108 system tokens aren't case sensitive anymore.
Strings you define yourself of course won't be translated to a special case.
Tokens may hold seperators, if they are enclosed in grouping characters.
These grouping character pairs are: () or [] or '' or "". The grouping
pairs may not nest. If an opener (bra) is encountered, the input line will
be copied to the token until the corresponding close character (ket) is
found.
Commandlines hold either a command or data. The line is interpreted as a
command, if it begins with a sharp sign '#'. In any other case DataProc
expects data to be there.
3 organization
Internally DataProc works much like a spread sheet program. It inits a table
of a user defined length and can add an arbitrary number of columns to it.
Commands usually affect a whole column. As you might guess the column is the
basic unit in DataProc. That is the major difference to a tabular calculator
where the cell serves as its unit.
Each column has one physical and two logical numbers. The physical is the
basic reference. It is simply the number of the column as it was declared
by the `columns` command.
Beyond that each column may be assigned a specific read column and a write
column, meaning the order data is read into them or written from them. For
more information see `using` and `ocol`.
3 mathematics
DataProc supplies a scientific calculator. You may define your own constants,
variables and functions. Read the following for its syntax:
ATOM - Atoms are plain Values like 7.65e-12 and constants like PH
Functions are treated as atoms as well, but the arguments
are itself Expressions
OPERATOR - The currently supported operators are + - * / ^ with the
commonly known meaning. Missing operators like in 3sin(x)
or 3 4 are treated as '*' so that the former expressions
would be expanded to 3*sin(x) and 3*4. Operators obey the
common priority rules.
BRACES - grouping characters. You may set Expressions into pairs of
corresponding braces. All types are treated equally, but
must of course match. The brace pairs are: [] {} ()
Thus (3*[4+5]-2)/6 would work but (3*[4+5)-2]/6 would not!
EXPRESSION - any valid combination of Atoms, Operators and Braces.
ATOM OPERATOR ATOM
EXPRESSION OPERATOR EXPRESSION
ATOM ATOM => OPERATOR = '*'
EXPRESSION EXPRESSION (dto.)
([{ EXPRESSION }]) => treated as ATOM in this
level
NAME - Names start with an alphabetic character and may be followed
by any combination of alphanumeric characters. The total
length must not exceed 29 characters. Names are not case
sensitive.
VARIABLE - NAME followed by OPERATOR or end of line
FUNCTION - NAME followed by an opening brace. In defines this must be
an opening parenthesis '('. Note that a defined VARIABLE
in the combination VARIABLE(... will be correctly interpreted
as VARIABLE*(... and a defined FUNCTION in the combination
FUNCTION EXPRESSION will lead to the message --> Argument
expected. Note also that spaces are ignored, except for
separation numbers, so that 3 4 is interpreted as 3*4 and
34 is interpreted as 34.
DEFINE - ":=" defines or redefines a variable or function. When
defining a function the next character must be '(' (spaces
are ignored)
VARIABLE:=EXPRESSION => define a symbolic
variable
FUNCTION(VARIABLE,...):=EXPRESSION => define a new function
Note that the template arguments are not stored to the
variable list. If identical entries exist in the variable
list they will not be recognized -- the template has higher
priority. Note as well that global variables are evaluated
immediately, so later changes won't affect the function.
COMMENTS - The line is terminated by any nonprintable character or a
semicolon <;>. The rest can be used for comments.
RESERVED - In future versions the following symbols may come to a
meaning, so do not put your own stuff on them! The charcters
are: ! _ _i _[]
`SYMBOLS`
The following symbols are predefined:
PI - you now that number (3.14...), don't you?
ME - the Euler number (2.718...)
RT2 - the square root of 2 (1.41...)
PH - Planck's quantum (6.626...e-34)
PHB - Planck's quantum divided by 2*PI
PE0 - electrical field constant SI (8.854...e-12)
PU0 - magnetical filed constant SI (1.256...e-6)
PC - light speed in m/s (2.997...e8)
PK - Boltmann constant (1.380...e-23)
PR - general gas constant (8.31441)
PSIGMA - Stefan-Boltzmann constant (5.670...e-8)
PE - charge of electron in C (1.602...e-19)
PME - mass of electron in kg (9.109...e-31)
PBM - Bohr's magneton in Am^2 (9.274...e-24)
PMP - mass of proton
PMN - mass of neutron
PF - gravity constant (6.672...e-11)
PG - standard earth acceleration (-9.80665)
PKEL0 - absulute zero temperature (-273.15)
PPN - normal pressure in Pa (101325)
PVM0 - ideal gas molaric volume in l (22.41...)
PNA - particles per mol (6.022...e23)
PFARAD - Faraday constant (9.648...e4)
PRH - Rydberg constant (1.097...e7)
PLC - Compton wavelength (2.426...e-12)
PSOLAR - solar constant (1.368e6)
N2KP - newton to kilopond (0.102)
MS2KMH - m/s to km/h (3.6)
J2MEV - Joule to MeV (6.241e12)
TORR2P - Torr to Pascal (133)
U2KG - u (nuclear mass unit) to kg (1.660...e-27)
KG2MEV - kg to equivalent energy in MeV (5.609...e29)
U2MEV - u to MeV (931.433...)
LY2M - light years to meters (9.465...e15)
AE2M - astronomic units to meters (1.495...e11)
PARSEC - Parsec to meters (3.085...e16)
IN2CM - inches to centimeters (2.54)
FT2CM - feet to centimeters (30.48)
YD2CM - yards to centimeters (91.44)
MILE2KM - miles to kilometers (1.609)
PS2KW - german horsepowers to kilowatts (0.736)
CAL2J - calories to Joule (4.1868)
EXA - scaling syllable (1e18)
PETA - (1e15)
TERA - (1e12)
GIGA - (1e9)
MEGA - (1e6)
KILO - (1e3)
HEKTO - (1e2)
DECA - (10)
DECI - (0.1)
CENTI - (1e-2)
MILLI - (1e-3)
MICRO - (1e-6)
NANO - (1e-9)
PICO - (1e-12)
FEMTO - (1e-15)
ATTO - (1e-18)
Arguments of trigonometric functions are expected in radian!
SIN(x) - sine function sin(x)
COS(x) - cosine function cos(x)
TAN(x) - tangent function tan(x)
COT(x) - cotangent function cot(x)
SEC(x) - secant function (1/sin) sec(x)
ASIN(x) - arcus sine function arc sin(x)
ACOS(x) - arcus cosine function arc cos(x)
ATAN(x) - arcus tangent function arc tan(x)
ACOT(x) - arcus cotangent function arc cot(x)
ASEC(x) - arcus secant function arc sec(x)
SINH(x) - hyperbolic sine sinh(x)
COSH(x) - hyperbolic cosine cosh(x)
TANH(x) - hyperbolic tangent tanh(x)
ASINH(x) - area hyperbolic sine ar sinh(x)
ACOSH(x) - area hyperbolic cosine ar cosh(x)
ATANH(x) - area hyperbolic tangent ar tanh(x)
SQR(x) - square of x -- faster than x^2 x^2
SQRT(x) - square root x^(.5)
ROOT(y,x) - yth root of x x^(1/y)
LN(x) - natural logarithm ln(x)
LG(x) - decadic logarithm log10(x)
LOG(y,x) - logarithm based y log_y(x)
EXP(x) - xth power of Euler constant e^x
FAC(x) - faculty of int(x) x!
RAD(x) - convert degree argument to radians
DEG(x) - convert radian argument to degrees
ABS(x) - absolute value |x|
SGN(x) - signum function sgn(x)
MAX(x,y) - returns the greater of x and y
MIN(x,y) - returns the smaller of x and y
Concluding Notes: Unlike most math programs the operator '/' is interpretd
as a fraction bar, so everything behind it is interpreted as the denomiator
unless an addition operator '+' or '-' is encountered. E.g.:
40/4*5 results in 2
15/45/9 results in 3
6/3+2 results in 4 (!)
There is a conceptional bug in the handling of the '-' operator. Do not
chain them. Instead write: EXPRESSION - (EXPRESSION + EXPRESSION). Also
the monadic '-' does not always work the way it should. (-ATOM) usually
does.
I won't fix the bugs in the math module, but I am going to completely
rewrite it, because the concept cannot hold sums, integrals, etc. The
new module will support integration and symbolic differentiation as
well.
2 commands
3 general
The command is the first `token` in a `commandline`. Commands always start
with a leading sharp sign '#'. Commands aren't case sensitive anymore.There
must not be any space between the sharp and the command.
As most commands affect one specific column there is a syntax that is
common to most commands:
#command col arg1 ...
where command is the command name and col is the physical 'column' to affect.
However, there are some commands that do not affect a specific column or more
than one, so col represents zero or more `tokens` in the general syntax. The
same is with the arguments.
Any `commandfile` must contain the commands `dsize` and `columns`. So read
the sections concerning those commands carefully.
3 variables
There are three types of variables maintained by the program that aren't
related in any way, may not be mixed up and cannot be processed together
in any way. Except for the fourth variable that may be build from two
of the latter.
The most important are the math processor's variables. Beyond what was said
in the math processor section, you may use them as data to write to columns
and `post` them on screen, by means of the equally named command. Specifying
"$=" in a `data` field makes a maths variable available to the data stream.
See the `data` section for more information about that. Math variables are
not cleared by the `reset` command.
Global variables -- it's just a name, math variables are of course global as
well -- are used to make the `commandfile` handier and more readable. Global
variables may replace any number `token` of any command, no care if it is
a column number, function number, row boundary or whatever. It will be much
easier to reference columns and functions by name than to keep track of
hundreds of abstract numbers. The `mark` command even frees you of the task
to count data rows for your boundaries. See `define`, `queue`, `mark` and
`undefine` for more information about global variables. Global variables
are cleared by the `reset` command.
Terminal enviroment variables are local variables, meaning that their value
is set per terminal. Two different terminals may carry different values in
equally name variables. On the other hand they are not cleared by the
`reset` command. They are used to provide the terminal with additional
information of how to produce their output. See `set`, `unset` and the
`terminal` section for more information about enviroment variables.
Since 1.159 `global strings` are supported. They are useful for two purposes.
First of all you can use computation results in `terminal enviroment`
variables, e.g. to add a fit curve to your data plot in the `GNUPLOT`
terminal. Secondary you can produce a better formatted output on
runtime.
3 addcol
This command adds a new column to an existing table. Normally you should
use the `columns` command for that task, but `addcol` might produce more
readable code or in some cases may cope with memory problems.
`addcol` must be followed by a number token, which is the physical column
number to generate. You may pass a name there and it will be assigned the
highest column number as a global variable. This is basically the way you
should use this function.
The second token must be a format identifier as specified in the `columns`
command.
Example:
#addcol LastCol %f
#row 0
#using LastCol
#include "MyData.tst"
This add a column behind all existing columns, reset the row counter and
read new data from "MyData.tst" to that column. LastCol would hold the
number of the new column.
See also `columns` and `remcol`.
3 applog
This command opens a file to store some scratch that you would usually
write on some sheet for further evaluation during the formulation of
your data analysis. If the file given with the first token already exists,
new lines will be appended to it.
See also `newlog`, `logline` and `logpost`.
3 areg
This is the most complex command implemented by now and it will hopefully
stay forever. `areg` enables you to do a least square approximation to any
function you like as long as you don't wish to optimize other than two
parameters. Note that for standard situations e.g. linear or logarithmic
regressions special commands are implemented so that you won't need this
command too often. See `lreg` and `logreg` for more information about
that.
The syntax is long but logical. The `tokens` are in sequence: x-column,
y-column, function to match, partial derivation of the function according
to the first parameter (a), partial derivation of the function according
to the second parameter (b), estimation for a and estimation for b. While
all of the latter tokens oblige the following may be omitted: iteration
depth, start row and finally end row.
The columns are indicated by their physical column number. The functions
are indicated by their number as assigned by the `func` command. For both
groups of numbers as well as for the start and end row, you may of course
use global variables. The functions are expected to take the parameters:
y=f(a,b,x)
in exactly that sequence. Take care that you only pass 3 parametred functions
matching the above convention.
The token contents for the estimation values are passed to the maths
processor, so you may use its math variables or even mathematical expressions
for the estimation values. Note that `areg` is usually rapidly convergent,
but false estimations my even crash the iteration.
If you pass zero to iteration depth or you omitted that token, `areg` will
work interactively. Thus it will stop after every iteration and show where
you are. If you're satisfied with the result, you leave the iteration
pressing the 'Q' key. Any other key will compute the next step.
Finally you may specify the first and last row of data to include in the
regression. Row numbers start with 1 and both rows given as boundaries
will be included. If you specify zero or leave the token empty the maximum
value will be set, meaning the first row as start or the last row as end.
The regression results are printed on screen during execution of the
`commandfile` and are stored to the math variables DPA holding the first
parameter result, DPB the second and DPSA and DPSB the corresponding
absolute errors.
See also `lreg`, `logreg` and `func`.
3 ask
Works just like `if` but the condition is given online by the user. The
rest of the line is promted to the screen and the user is asked to
enter 'Y' or 'J' for a true condition or 'N' for a false condition. The
command must further be handeled by `else` and `endif`.
Note that setting a batch level higher or equal to 10 will always answer
this command with 'N'.
Example:
#ask Shall I do it?
! I did it!
#else
! why not?
#endif
will print on screen "Shall I do it? (Y/J,N) > " If you type 'N', it will
post "why not?" or if you type 'Y' or 'J', it will post "I did it!"
See also `if`, `else`, `endif`, `readvar`, `stop` and `batch`.
3 average
Followed by the `column` to average, an optional weight column that may be
left empty and the start and ending row, which as well may be left empty or
set zero.
If a weight is specified DataProc computes the average to the weight given
in the designated column.
If the startrow `token` is empty or zero the first row is defaulted. The
analogon is an empty or zero `token` for endrow that is interpreted as the
last row currently read.
The results of the average computation is posted on screen during the
execution of the `commandfile`. The results are also stored to global
variables that may be accessed by the maths processor. DPMX holds the
computed mean and DPSMX its absolute error. DPMSX holds the average
absolute error (standard deviation). Those can be further processed using
`math`, `post` and `generate`.
Example:
#average 3
! The average peripherial length is
#post dpmx*pi
computes the unweighted average of all entries in column 3. If we assume
that column 3 holds the results of several attempts to measure the diameter
of a circle, it finally posts the average length of the peripherial on
screen.
See also `mean`, `math`, `generate`, `post` and `lreg`.
3 batch
This command sets a so called batch level. The next token must be a
number token, which is set as batch level. Default is batchlevel 0.
Any nonzero level will ignore all `stop` commands. A level higher
or equal to 10 will answer any `ask` command with 'N'.
See also `ask` and `stop`.
3 build
This command is used to assemble `global string` variables. It acts much
like typical print commands in many programming languages. The arguments
in sequence are: variable name, format string, arguments. Note that the
argument line is parsed as tokens, thus you will usually have to quote
the format string or mathematical expressions.
The format string may contain %d (%ld) what believes the corresponding
argument to be a `global variable`, %f (%lf) is replaced by the result
of the given mathematical expression, %s what denotes a pure string or
a `global string` variable and finally %% producing the percent itself.
%f (%lf) may be followed by a single digit denoting the number of
significant cyphers just like the `prec` command. The precision defaults
to 7.
Global strings can be evaluated by `build`, `post`, `preamble` and `set`.
Example:
#build mystr "The mean pressure is: %f +/- %f hPa" DPMX DPSMX
#post mystr
This makes your script's runtime output a little more readable.
3 closelog
Closes a note sheet file that has been opened by `newlog` or `applog`.
Usually you won't need this command, because DataProc closes all files
when closing down. Anyhow, if you like to print out your logfile during
execution, you must close it, before another application may open it
for further processing.
Example:
#applog "mylog.log"
; do something
#closelog
#dos type mylog.log
Will print out the log file "mylog.log" that had been generated or modified
in the same commandfile.
See also `closetag`, `newlog` and `applog`.
3 closetag
Closes a tag database file that has been opened by `tagfile`. Usually you
won't need this command as DataProc closes all files when closing down.
Anyhow, if you want other applications to work with it, before your
commandfile ends, you may make it accessible by this command. See `closelog`
for a typical application.
See also `tagfile` and `closelog`.
3 columns
The first `token` is expected to hold the number of columns for the table
to hold. Since version 1.204 this token is optional and may be omitted. If
you supply a number of columns it will be used. Note that any format
identifier beyond that mark will be ignored and if you supply less
identifiers this will cause an error.
The next tokens hold format descriptors for the relating column. They are
just like the printf() C type format descriptors.
%f - float number
%lf - float number (synonym to %f)
%d - integer number
%s - character string
The sequence the columns are declared in makes their physical `column`
number. E.g.:
#columns 3 %d %f %s
would allocate space for three columns and declare the physical column
number 1 to hold integer numbers, physical column 2 to hold floats and
physical column 3 to hold strings.
In addition the logical read and write numbers of the columns are inited
to the physical column number.
See also `dsize` and `reset`.
3 contract
This command is quite similar to `generate`. But unlike `generate` it
produces a new column by processing entries of the same column. It could
be used to compute the deltas between to entries, but that is already done
by `delta`.
The first `token` holds the column to generate. Then the start and end row
follow. Empty tokens there or zeroes are interpreted as boundary values,
meaning first or last row. The next `token` holds the stepwidth, meaning
the distance between two rows to process together. So if you have a `data`
stream holding the occurences of maxima and minima, a stepwidth of 2 would
serve to compute the e.g. deltas between maxima and minima without mixing
them up. The next `token` holds the function number to use for processing.
The following tokens build a column list, so you can use the information of
more than one column.
The function arguments are passed in the following manner: Current row of
the first `column` in the list, current row plus stepwidth of the first
`column` in the list, current row of the second column in the list and so
on.
The destination is written to the destination column at current row plus
stepwidth. The first stepwidth rows in the destination are thusly marked
void.
The row boundaries refer to the current row. Each row between the first and
last minus stepwidth may become current row, if you select that range.
Example:
#func 1 f(u1,u2,i1,i2):=(u2-u1)*(i2-i1)
#contract 5 0 0 2 1 3 4
Writes the product of the differences of odd and even row pairs in columns
3 and 4 to column 5. As the whole range is selected any possible pair in
forward sequence will be processed. The first two entries in column 5 will
be marked void.
See also `func`, `generate` and `delta`.
3 count
Fills a column with the current row number. An optional function as defined
by a `func` command may follow. In the latter case the column will hold the
results of the given function, which is passed the row number as its
argument.
Example:
#func 1 f(x):=10x+3
#count 1
#count 2 1
The first command stores the row number to column 1. The second stores the
row number multiplied by 10 incremented 3 to column 2.
See also `func`, `make` and `scale`.
3 define
Defines a global variable. Global variables may replace `any token` that
expects numbers. No matter if it be column numbers, function numbers, row
boundaries, etc. They however aren't related in any way to the math
processor's variables and thus cannot be used in mathematical contexts.
The syntax is variable name followed by value. Example:
#define MyVar 6
`MyVar` may now replace any number `token` with the value 6. For instance:
#lreg 1 2 3 myvar
would do a linear regression of column 2 to 1 weighted by 3, beginning with
row myvar -- which we defined to be 6. As you probably guess from that,
global variables -- being `system tokens` -- are not case sensitive.
See also `undefine`, `queue` and `mark`.
3 delta
Works similar to `contract` with the function f(x,y):=y-x as the inbuilt,
eternal and unchangeable default. Thus the function `token` is missing.
The first `token` holds the column to generate. The next `token` holds the
`column` to take the `data` from. If the next `token` holds a '-' sign,
the function result is negated, resulting in f(x,y):=x-y. If this `token`
does not hold a '-' it is directly interpreted as the next one, which holds
the start row and the next the end row. As usual empty or zero tokens mean
boundary values that is first or last row. The first entry in the
destination column is marked void.
See also `contract`.
3 diff
Computes the average difference of the entries in a column in a better and
faster way then a combined `delta` and `average`. It uses the so called
"far differences method" which produces much better results than the above,
if you have more than 6 items. The item count however must be even or the
last item will be ignored.
The first `token` holds the column to process and the second may optionally
hold a weight column. By now the latter is simply averaged to compute a mean
error, which is in turn stored to DPSMX. The mean itself is posted on screen
and of course stored to the global maths variable DPMX.
Example:
#diff 3
! Wavelength
#post 2DPMX
Suppose column 3 holds the coordinates where zero amplitudes of a standing
wave have been encountered. `diff` computes the average difference between
those coordinates that is half the wavelength. The `post` command doubles it
and puts the result on screen.
See also `average`, `delta` and `post`.
3 digital
Sets the `precision` fixed to the decimal point for the column. The argument
is the decadic exponent of the last significant cypher.
Example:
#digital 2 -2
#digital 3 1
will cause the number 123.456 to appear as 123.46 in column 2 and as 120 in
column 3.
Beyond that a minimum error is computed for that column which is used in
averaging, etc. when no error column is specified to avoid meaningless
results.
See also `prec` and `average`.
3 dos
This command passes whatever it is followed by to the operating system's
command processor.
Example:
#term gnuplot
#write "MyPlot.dta" "MyPlot.gnu"
#dos gnuplot MyPlot.gnu
will imediately plot your results.
3 dsize
Sets the maximum number of rows that all columns of the table may hold. This
command should preceed the `columns` command.
If no `dsize` command preceeds the `columns` command, `columns` will default
the table size to 10 rows. If a table exceeds the given size, DataProc will
try to enlarge it, by either doubling the current size or adding 100 rows,
whatever is smaller. Note that this might cause memory fragmentation and
takes some time, if you have a lot of columns. So if you encouter memory
problems, try to specify a tight -- but sufficient -- `dsize`.
`dsize` may now appear anywhere in the commandfile. Note that in previous
releases this might have caused severe crashes. Anyhow, you cannot shrink
tables. If you specify a size smaller than the current size, `dsize` will
be ignored. If you want to save memory during runtime shrinking a table,
you must `reset`.
Example:
#dsize 40
Sets the maximum number of rows in the data file to 40.
See also `columns` and `reset`.
3 else
Will switch to the other condition of an `if` statement. If the last
`if` already encountered an `else`, it will cancel this `if` and
`else` refers to the previous nesting level.
See also `if`, `endif` and `ask`.
3 endif
Cancelles an `if` nesting level and returns to non conditional execution.
See also `if` and `else`.
3 exit
Causes DataProc to terminate immediately. Any further data either in
the current or the parental file or files will be ignored.
See also `quit`.
3 flushset
Annihilates all assignments to terminal enviroment variables done by
`storeset` at one time.
Example:
; adapt to german language and EEPIC output
#include deutEEP
; do something
; prepare output for a doubly logarithmic regression
#term latex
#storeset aID Exponent
; produce some output
; and return to the "deutEEP" settings
#flushset
See also `storeset`, `set` and `reset`.
3 flushvar
This function clears all global constants. I'm not sure, if you might have
need for it, because `reset` does this as well, but if you should, here it
is.
See also `reset`.
3 func
The next `token` numbers a function that is explained in the rest of the line
to the maths processor. By this number `make`, `count` and `scale` reference
their functions. Note that since 1.231 you may place an undefined global
variable instead of a defined number token. DataProc will seek for an empty
slot and define the global with the number it assigned the function.
The name of the arguments are arbitrary, but the sequence left to right
corresponds to the left to right sequence how `make` passes the cell values
of its designated argument columns.
Example:
#func 4 c(a,b):=a/b
#func 5 errc(a,b,sa,sb,c):=c*sqrt((sa/a)^2+(sb/b)^2)
Computes a value c as the quotient of a and b and its error by the Gauss
error propagation for potency expressions. The `make` command my look as
follows:
#make 5 4 1 3
#make 6 5 1 2 3 4 5
This would expect a to be in column 1, its error in 2, b in 3, its error
in 4 and would generate the quotient c to column 5 and its error to 6.
See also `make`, `count`, `scale`, `generate` and `math`.
3 generate
This command is similar to `make`. The difference is that it does not
execute during the `data` read, but it does generate a new column immediately
from the already read table.
The syntax differs a little from `make`. The first `token` holds the column
number to generate. The next two tokens hold the start and end row to
process. Empty tokens or zeroes are interpreted as boundary values, meaning
first and last row. The next token holds the function number. The value -1
calls the inbuilt function that results with the row number. The following
tokens are just as `make` the function arguments.
Example:
well we read some data to column 1 and 2 ...
#lreg 1 2
#func 1 delta(x,y):=abs(y-DPA*x-DPB)
#generate 3 0 0 8 1 2
Column 3 will then hold the absolute difference to the mean straight line.
See also `make`, `columns` and `func`.
3 globtitle
globtitle sets a global title to the whole table. The next `token` is
interpreted as a string which is used to name the table. See the
`terminal` section for more information about titles.
See also `title`.
3 group
The first `token` is expected to hold a group number. If the group number is
new, a new group is allocated. The following tokens hold a list of columns
to add to the group. You cannot shrink a group by now.
Grouping is mainly a formatting advise for the `terminal` driver. Table
drivers for instance should equip groups with a common title as specified
by the `name` command.
Example:
#group 1 5 6
#group 1 7
#group 1 6
The first command allocates the group 1 and specifies the columns 5 and 6 as
its members. The second command adds column 7 to the same group that now
holds the columns 5, 6 and 7. As column 6 is already in the group the third
command is ignored.
See also `globtitle`, `title` and `name`.
3 gtitle
Sets a secondary title to a column. Works just as `title`, but the argument
string is stored to a different place. This title should be used to e.g.
name the points in a plot. See the `terminal` section for more information
about titles.
Example:
#gtitle 2 "Counter rates"
Sets the gtitle to "Counter rates". The gnuplot terminal will thus name the
data plot "Counter rates".
See also `title` and `rtitle`.
3 if
Initiates a conditional block of statements. The rest of the line is passed
to the maths processor and the result is checked. Any value greater than
zero denotes TRUE, zero or less FALSE.
If FALSE, control will not execute any command until `else` or `endif` is
encountered.
If TRUE, control will continue execution until `else` is encountered. In
that case the block will be skipped until `endif` appeares. `else` is of
course not obligatory.
See also `else`, `endif` and `ask`.
3 include
The following `token` is the filename to include. If the file does not open,
DataProc retries filename.tst and if that fails, too, it issues a "File does
not exits" error. The include file is expected to be a `commandfile`, just
like the one calling for `include`. This is especially handy, if you e.g.
create your data automatically and have to process them just the same
every time. So you would write a commandfile inputting theese data. Another
extremely practical usage is to create a datafile by the current script
and reread the preprocessed data after resetting the table to the same
script. Well, possibilities seem infinite.
Whatever is in the file is handeled as if it were part of the original file.
You may nest `include` as deep you will. As the algorithm is recursive you
may be well advised to increase stack for extremely deep include nests. On
other machines like MS-DOS you might have to increase the FILES entry in
your config.sys, but DataProc's concept has no problem with deep nesting.
You should however ensure, that you do not create include loops, meaning a
subfile including one of its parentals. DataProc doesn't check that and will
crash sooner or later, because of stack leakage or other system odds.
Depending on the runtime system of the compiler it might even leave files
open, what may have severe consequences to your filesystem. On some systems
the medium will become unreadable and will have to be reformatted!!!
3 leave
Works similar to `slip` but marks the column to permanently hold misresults
until a `take` command disables `leave`. This command is used to exclude
groups of results from a regression, e.g. a non linear area.
The argument `token` holds the column number to mark as misresults. If the
column number zero is specified `leave` marks all read columns as misresults.
Note the the column number refers to the logical read column as assigned by
`using`.
Anything that is gained by further processes of a marked entry (e.g. by
`make` or `generate`) is also marked.
See also `make`, `using`, `columns`, `slip` and `take`.
3 logline
Whatever follows the command will be written to the current logfile. If no
logfile is opened, the command will be ignored.
Example:
#newlog "Important.log"
#logline Now comes the most important thing ever!
Will open a new file called "Important.log" overwriting existing an existing
file and write "Now comes the most important thing ever!" to it.
See also `applog`, `logpost` and `newlog`.
3 logpost
Works exactly like `post`, but redirects its output to the current logfile.
If you did not open any logfile, the command is ignored.
See also `applog`, `logline`, `newlog` and `post`.
3 logreg
Works just like `lreg`, but the first `token` is interpreted as a regression
mode. Specifying zero makes this command equivalent to `lreg`. One causes
logarithmic scaling on the x-axis, two on the y-axis and 3 on both.
This command uses the decadic logarithm. The results that are posted to the
terminal and set to DPA, DPB, DPSA, DPSB and DPR are the parameters of the
straight line. It is the user's task and the task of the `terminal` drivers
to interpret theese results correctly.
For more information see `lreg`.
3 lreg
Starts a linear regression. The arguments are: x-column, y-column, y-weight,
startrow and endrow. Only the first two cannot be omitted. An empty or zero
startrow or endrow sets this value to firstrow or lastrow.
If a weight column is specified a weighted regression will be done. If not,
well DataProc does a simple regression.
The regression results are hooked to the y-column. Output terminals may care
to output them when outputting the y-column. See the `terminal` section for
more information.
Beyond that the variable DPA, DPB, DPSA, DPSB and DPR of the math processor
are set to the regression results. Where DPA holds ascend of the regression
straight line, DPSA its error, DPB the y-offset and DPSB the error of the
latter and DPR the correlation ratio.
Regression results are monitored to 'stdout' (usually the screen) during
execution of the `commandfile`.
Example:
#lreg 1 3//8 0
Does an unweighted linear regression of column 3 against column 1 beginning
with row number 8.
See also `logreg`, `areg`, `average`, `math` and `post`.
3 make
This command specifies a function to generate an entry in a column from a
number of entries in other columns. All entries belong to the same row.
Note that `make` won't overwrite valid data. If you want it to, use `void`
to mark it invalid.
The first `token` designates the column to generate, the second the function
number to use (see `func` for more info) and the following tokens are the
column numbers which the function arguments are to be taken from.
Example:
#make 3 1 4 5
generates the entries of column 3 using the function 1 passing it the
contents of columns 4 and 5 as arguments each row. The whole thing might
look as follows:
#func 1 f(x,y):=x+y
#using 4 5
#make 3 1 4 5
would read the data in the file to columns 4 and 5 and would store their
sum in column 3.
The sequence of the `make` commands is irrelevant. Before execution they
are sorted as necessary that all columns hold valid data before being
passed as arguments. An error will be issued, if that is not possible.
See also `func`, `count`, `generate`, `scale`, `undo` and `void`.
3 mark
This command is used to `define` a global variable to the current row number.
It is helpful to make row boundaries easier -- you don't have to count
anymore -- and more transparent. The only argument is the name of the variable
to define. Note that you cannot redefine variables. Use `undefine` to free
them first.
Example:
some data here ...
#mark RegStart
some data there ...
#mark RegEnd
and there may be still some ...
#lreg 1 2//RegStart RegEnd
This would cause `lreg` to do an unweighted regression of column 2 to 1
beginning with the data set following the #mark RegStart and ending with
the data set following #mark RegEnd -- both inclusive.
See also `define`, `undefine` and `queue`.
3 math
Whatever follows this command is directly passed to the maths processor.
You will usually use it to compute results from regression data and use
them as constants in new functions or `post` them on screen.
Example:
#title 1 diameter
#unit 1 cm
#digital 1 -2
#using 1
then some data follows
#average 1
#math l:=mx*pi
#math sl:=smx*pi
! The average length of the peripherial is
#post l
! with an average error of
#post sl
Well, that speaks for itself, doesn't it?
See also `func` and `post`.
3 mean
Works similar to `make`, but you cannot choose an arbitrary function. As
with `make` the first `token` holds the destination `column`. The next
tokens hold a list of source columns. The entries of the destination
columns are filled with the mean of the source columns during the `data`
reading procedure.
You can reference the error of the mean using the `smean` command.
Example:
#mean 6 1 2 3 4 5
#smean 7 6
Stores the mean of columns 1 thru 5 to column 6 and the error of the mean
to column 7.
See also `smean`, `make` and `average`.
3 meanof
In many cases you need the average of a well defined set of values for
further computation. `meanof` frees you of the task of typing it as two
`math` lines. The syntax is pretty simple. The first token holds the
name to store the average to, the second the name of its error, then
a list of maths expressions must follow. Note that you must at least
supply two expression tokens. Beyond that the total number is arbitrary.
Example:
#meanof mr smr r1 "2*r2" 123
Will compute the average of r1, (2*r2) and 123 and store it to mr. The
average spot check error.
See also `mean` and `wmeanof`.
3 merge
Adds up to 20 columns to a data column for output purposes. This is used
to plot more than one column's data in a single diagram by means of the
"gnuplot" terminal driver. See the `terminal` section for more information
of how the terminals handle merges.
Example:
#merge 2 5 6 7
well, there might be anything
#term gnuplot
#ocol 1 2
#write "data.dta" "data.gnu"
This will produce a graph showing the behaviour of the y-data in coloumns
2 5 6 and 7 to the x-data in column 1. Without the `merge` command only the
data in column 2 would be taken.
See also `ocol` and `write`.
3 name
This command sets a title common to a group. If you are measuring for
example a set of parameters of a gas at different pressures, you would
put all measuring series to a common pressure into a group and name it
according to the pressure used.
The first `token` holds the group number as specified by a `group` command.
The second `token` holds the title for the group.
Example:
#group 1 1 2 3
#group 2 4 5 6
#group 3 7 8 9
#name 1 "700 mbar"
#name 2 "800 mbar"
#name 3 "900 mbar"
See also `group`, `globtitle` and `title`.
3 newlog
This command opens a file to store some scratch that you would usually
write on some sheet for further evaluation during the formulation of
your data analysis. If the file given with the first token already exists,
it will be overwritten.
See also `applog`, `logline` and `logpost`.
3 nop
No operation. This command does absolutely nothing and is only a kludge
for debugging purposes.
3 ocol
This command is followed by a list of physical `column` numbers. The
terminal output is generated from that list in the given sequence. It
also assigns the logical write numbers of the columns. It is the pendant
to `using` doing the same for data input.
Example:
#term gnuplot
#ocol 2 9 7
#write "data.dta" "data.gnu"
This will output in sequence the columns 2, 9 and 7 to "data.dta". The
"gnuplot" `terminal` will interpret that as x-data, y-data and y-errors
and will thus output the corresponding command sequence to "data.gnu".
See also `term`, `write` and `using`.
3 post
Whatever stands behind `post` is passed to the maths processor, unless
the first token is found as a `global string` as defined in `build`.
The result is then printed on screen during execution of the `commandfile`.
See `math` for an example. See also `build`, `func`, `lreg` and `average`.
3 preamble
The string following this command is set in front of any terminal output
via `write`. Internally the string is passed to an fprintf() function,
so mind the C type character specials. If the first token is found to
be a `global string` as defined by `build` its contents are used to
fill the preamble.
Future versions will support the printout of internal values, but this is
not yet implemented. Even the C type formatting characters don't seem to
work properly.
Example:
#term gnuplot
#preamble 'set terminal eepic; set size 1,1.5; set output "data.gph"'
These commands select the GnuPlot driver as output terminal and the preamble
in turn inits GnuPlot to output an EEPIC data file to "data.gph" in my
preferred size.
See also `term`, `write` and `unamble`.
3 prec
Sets the precision for one column or defaults it for all columns if the column
number 0 is passed. Precision means the number of significant cyphers to
display. It does not affect the internal computations.
Example:
#prec 0 4
#prec 1 5
will at first default the precision to 4 significant cyphers for all columns
and then define the higher precision 5 for column 1. Thus:
3.0145 will result 3.0145 and in column 1: 3.0145
3.01458 will result 3.0146 and in column 1: 3.01458 (last digit rounded)
0.0003 will result 300e-6 and in column 1: 0.0003 (exponents are
multiples of 3)
etc.
See also `digital`.
3 queue
Defines a chain of global variables, meaning a number of those with following
numbers. This is especially useful, if you want to name the coloumns of your
table. The first entry is expected to hold the value of the first global
variable in the list. This may of course also be a global variable. The
following tokens hold an arbitrary list of global variables to `define`. Note
that you cannot redefine variables, use `undefine` to free them first.
Example:
#queue 3 myvar1 myvar2 myvar3
would set myvar1 to 3, myvar2 to 4 and myvar3 to 5.
See also `define`, `undefine` and `mark`.
3 quit
Causes DataProc to terminate the current file. In the main commandfile
this will terminate execution -- just like `exit`. In children files
this will return control to the parent.
See also `exit` and `include`.
3 read
Well, for all practical purposes this command became meaningless. You should
not use it. It redefines the format of logical read columns. The syntax is
just like the `columns` command, but the identifiers refer to the logical
read columns and not to physical columns.
See also `using` and `columns`.
3 readvar
This command enables you to define math variables during runtime. The
first token holds the variable name, the rest of the line is posted
to the screen and a prompt is added. Execution waits for a float number
to be entered and will assign its value to the given variable.
See also `ask` and `stop`.
3 remcol
Removes a column from the current table. `remcol` must be followed by a
physical column number. I am not sure, if it is always save to use that
function, but if you are in trouble with memory space, you might welcome
this function. Anyhow, if you find crashes that may be caused by `remcol`
report them and I will see what I can do.
See also `addcol` and `columns`.
3 reset
Starts a new table and thus forgets all columns, regressions, etc. that have
been done previously. The math processor is however not affected by reset and
thus all variables, constants and functions are still available.
reset attempts to free all the memory allocated by table private structures.
I am not sure if it is always succesful in freeing everything. So if you
should have memory troubles a reorganization of the `commandfile` may take
you out of there.
After processing reset the declarations for `dsize` and `columns` must be
newly set, because the previous are forgotten and deallocated. Global
variables are also forgotten. Terminal enviroment variables however are
not affected by `reset`.
See also `dsize`, `define`, `set` and `columns`.
3 row
Sets the row counter to the specified value. This is useful especially
to read data for different columns from different files as well as to
partially replace data in an already made table. Be careful using this
command, you can easily produce "white spots" in your table. The command
only checks that you do not exceed the maximum size as defined by the
`dsize` command.
Example:
#using 1
#include "Col1.dta"
#row 0
#using 2
#include "Col2.dta"
This would read column one from "Col1.dta" and later read the same rows
but in column two from "Col2.dta".
See also `using`, `include`, `void`.
3 rtitle
Sets a secondary title to a column. Works just as `title`, but the argument
string is stored to a different place. This title should be used to e.g.
name the regression graph in a plot. See the `terminal` section for more
information about titles.
See also `title`, `gtitle` and `runit`.
3 runit
Sets a secondary unit to a column. Works just as `unit`, but the argument
string is stored to a different place. This title should be used for
hybrid units like in regressions. If no `runit` is specified, the terminals
should care to create their own hybrids. See the `terminal` section for
more information about units.
See also `unit`, `runit`, `gtitle` and `title`.
3 scale
Sets a function to scale data before storing it to the table. The function
must expect one argument of course. `scale` expects the physical column
number.
Example:
#func 1 f(x):=x/milli
#scale 2 1
For example the data unit of column 2 may be meters, but you measured
millimeters and thus copied them to the `data` section. The `scale`
command will care for that problem and divide all values by milli.
3 set
Sets a terminal enviroment variable. Please refer to the `terminal` section
for the meaning of such variables to the terminals. The first `token` is
expected to be the variable name and whatever follows will be stripped of
leading and trailing spaces and set to the variable value, unless the first
token is identified as a `global string` as defined by `build` what sets
its contents.
The variable is -- just as the `preamble` -- hooked on the terminal. It will
not be affected by `reset` and each terminal holds its own set of enviroment
variables. Thus you must first activate the terminal, you want to change the
variable in (see `term`). `set` redefines without any warnings, unlike e.g.
`define`.
Example:
#set output myfile.gph
#set author Lars Hanke
sets the enviroment variable "output" to "myfile.gph" and "author" to
"Lars Hanke". Note that the variable name is a system token and thus not
case sensitive.
See also `unset` and `term`.
3 slip
Marks the following row of the specified column or of all columns, if column
number 0 is given, a misresult that should not be used for regression or
averaging. Note that anything computed from that entry e.g. by `make` or
`generate` will bear the same mark. Also note the the `diff` command will
ususally produce bad results, if an item is left out.
The first `token` holds the `column` to affect. If zero is specified it
affects all column `data` is read to. Other tokens are ignored. `slip` is
only valid for one single row. It is used to mark one single misresult.
Note that the column number refers to the logical read column as assigned
by `using`.
Example:
3/3/1
#slip 2
4/9/1
5/5/1
Obviously the result should have been something like 4/4/1 and 4/9/1 will
destroy any good regression, so this single line will not be considered by
a later `lreg` command.
See also `average`, `lreg`, `diff`, `using`, `columns`, `leave` and `take`.
3 smean
This stores the error of the last `mean` command to a new column. The first
`token` holds the column to store the error to and the second `token` holds
the column the `mean` was stored to. The whole thing is done during the
`data` read procedure.
See also `mean`.
3 stop
Promts the rest of the line on screen and waits for any key to be pressed.
You should use this function to stop a screen scrolling by and watch some
results.
Note that a nonzero batch level will cause this command to always continue.
See also `batch`.
3 storekill
This command is used to locally unset a terminal enviroment variable.
The syntax and function is equivalent to `unset`, but this command is
tracked and the variable will be restored with a call to `flushset`.
See also `flushset`, `storeset` and `unset`.
3 storeset
This command is used to locally set a terminal enviroment variable. The
syntax is exactly equal to `set`, but this command is tracked and may
be annihilated by `flushset`. This is useful, if you preset your
terminals with e.g. a language definition file and want to change some
settings for a specific output.
3 tagdata
Produces a clear data entry to a tagfile. Accepts an arbitrary number of
arguments that may be global strings or math expressions. Note that all
arguments are tokens. The arguments are evaluated and written to the
tagfile using the separator given in the first token. If the first token
is longer than a single character, it will be evaluated as first data entry
and the separator will default to '/'.
Example:
#tagdata & mystr 3*4 2+pi
will write "(contents of mystr)&12&5.14..." to the tagfile
See also `tagfile` and `tagpost`.
3 tagfile
Opens a tagfile or - if you would rather have it - only one tag. A tagfile
is a textfile containing marks which areas belong to which source files.
You may post an arbitrary number of lines to each tag and finally read it
as an input file for DataProc again. As all tags are assured to start with
a comment, DataProc won't notice them while rereading such a file.
The syntax is tagfilename in the first and tagname in the second token.
The tagname may be a global string.
Calling `tagfile` automatically closes previously opened tagfiles and
automatically appends new tags, if the given tag is not in the file. It
also creates new tagfiles, if the given filename is not found.
Example:
[something computed the maths: amp amperr DPA DPSA DblDPA DblDPSA]
#tagfile "MyTags" File1Results
#build regress1 "%f/%f/%f/%f" amp amperr DPA DPSA
#build regress2 "%f/%f/%f/%f" 2*amp 2*amperr DblDPA DblDPSA
#tagpost regress1
#tagpost regress2
This would always maintain two data entries in the tagfile "MyTags". You
may later reread the tagfile as input for another table. This is extremely
useful, if you have to regress or average the results of several regressions
or averages of different tables.
See also `tagpost` and `newlog`.
3 tagpost
Works exactly like `post`, but the results are written to the current tagfile.
If no tagfile exists, the command will be ignored.
See also: `tagfile`, `post` and `logpost`.
3 take
Removes the misresult tag set by `leave` from a column or from all columns
if column number zero is specified.
The argument `token` holds the logical read column to affect.
See also `leave`.
3 term
Specifies an output terminal driver. The next `token` is expected to be
the terminal name. For more information about terminals and output see
the `terminal` section.
See also `write`.
3 title
Sets a title to a specific column. The command has standard syntax. The
argument `token` holds the string to be used as the column's title. See
the `terminal` section for more information about titles.
Example:
#title 2 Speed
Sets the title "Speed" to the physical column 2.
See also `gtitle`, `rtitle`, `unit` and `globtitle`
3 unamble
Deletes a `preamble` from a terminal. Just to get rid of formerly defined
terminal initialization strings.
See also `term` and `preamble`.
3 undefine
Cancelles a global variable as defined by `define`, `queue` or `mark`. It
also frees its memory. You may pass as many variables as you like to free.
Example:
#undefine myvar1 myvar2 myvar3
will free all the 3 variables named. If a variable is not found, `undefine`
doesn't care.
See also `define`, `queue` and `mark`.
3 undo
Removes a `make` directive from a column and thus stops its automatic
generation. `undo` removes `mean` and `smean` directives as well.
Example:
#make 3 1 4 5
column 3 is now generated using function 1 with columns 4 and 5
as function arguments.
#undo 3
column 3 won't be generated any longer
See also `make`, `mean` and `smean`.
3 unit
Set the name of the unit in the specific column. In fact this is nothing
else than another `title`. The terminals care for a handling of the unit
string as a unit. See the `terminal` section for more information about
titles and units.
Example:
#unit 4 cm
#unit 2 "\frac{\mbox{m}}{\mbox{s}}"
Sets the unit of the physical column 4 to cm and of column 2 to a LaTeX
style command to issue m/s.
See also `title`.
3 unset
Deletes an enviroment variable as defined by `set` from a terminal. See
`set` and the `terminal` section for more information about enviroment
variables.
`unset` may be passed an arbitrary list of enviroment variables. It will
attempt to free all of them and won't mind, if any of them exist.
Example:
#unset author output
will free both variables "author" and "output".
See also `set` and `term`.
3 using
This command assigns the logical read column numbers. using is followed by
a list of physical column numbers that are in turn assigned logical read
columns in the given sequence. Columns that do not appear in the list
will not be read.
Example:
#using 3 6 1
will read the first data `token` into the physical column 3, the second
`token` to column 6 and the third to column 1. Any further data tokens
are ignored.
See the `data` section for more information about data tokens, etc.
See also `columns` and `ocol`.
3 void
This command marks a block of rows in a column as invalid. The syntax is
in sequence: column to affect, first row to mark void and last row to
mark void, both inclusively. As the `make` command does not overwrite
valid columns, `void` can be used to enable remakes in a second read
pass realized by resetting the row counter using the `row` command.
See also `row` and `make`.
3 wmeanof
This function fulfills the same task as `meanof` but is its weighted
derivant. The first token holds the variable name to store the average
to and the second the variable name to store its spot check error. These
tokens are followed by pairs of maths expressions denoting value and their
errors each. Note that you must at least supply two pairs -- that is
six tokens all in all!
See also `meanof`.
3 write
Followed by one to four tokens. The first `token` holds the name of the
output file to write to. The second `token` supplies a secondary filename
for additional information that is needed by some terminals.
The last two tokens hold start and endrow, which are both included. Empty
tokens or zeroes are interpreted as maximum values -- meaning first or
last row.
What columns are written depends on their logical write numbers. See `ocol`
for information about assigning logical write numbers.
What files are needed, how many columns may be passed and how that is
interpreted depends on the selected `terminal`. See the `terminal` section
for more information about that.
Example:
#write "data.dta" "data.gnu" 0 8
#write "dat1.dta" //9
Writes from the first row to row number 8 to "data.dta" and passes the name
"data.gnu" for the driver file. Then outputs the rest to "dat1.dta"
specifying no driver file.
See also `ocol` and `term`.
2 data
Any line that cannot be processed as a `command`, `comment` or `post` is
expected to hold `data`. Data lines are series of tokens. Each `token` is
read to a logical read column as defined by `using` in the sequence of
their occurence. An empty or missing `token` causes DataProc to copy the
last entry again.
If the first `token` for a column is read empty the default value on startup
is void.
Example:
#using 1 2 3
#math lv:=2*3.9
1/2.1
2/3.5/6
3/4.7
4/5.2/3
5/6.1
6/6.8
7/7.2/-
8/7.5
9/$=lv
would result in a table:
1 2.1 -
2 3.5 6
3 4.7 6
4 5.2 3
5 6.1 3
6 6.8 3
7 7.2 -
8 7.5 -
9 7.8 -
A `token` is marked void, if the last character is a '-' sign. That does
however not apply to string typed data. It is also possible to read in
variables from the maths processor as shown in the last line of the above
example. The magical sequence '$=' causes DataProc to seek for a variable
that is named as the rest of the `token` and put its value there. This
feature works with double typed columns as well as with integer typed
columns.
2 terminals
Together with the regression facilities this is the most useful and complex
section. DataProc can issue `data` correctly formatted for a number of other
programs. DataProc generates LaTeX tables (tabular enviroments) using the
`latex` terminal driver, GNUPLOT data and command files using the `gnuplot`
terminal and several other terminal e.g. `plain` which produces a printer
output comes with this version. Read this section carefully, because some
terminals may handle some situations absolutely different from others.
All terminals support preambles, which are outputted at the beginnig of the
secondary outputfile. If there is no secondary file for the specified
terminal, the preamble goes to the primary. All terminals support backslash
controls in their preambles.
See also `commands write` and `commands ocol` for the definition of primary
and secondary output files, logical write columns, etc. See `commands term`
to select a terminal for output.
Terminal names aren't case sensitive anymore, for they are system tokens.
3 backslash controls
Some `terminal enviroment variables` allow non-printable characters, or you
may wish to set linefeeds etc. into `preambles`. Therefore you may set
backslash control sequences. They all begin with the `backslash` '\'. The
definitions of those sequences is similar to the C-language character
definition. Note that by now you may set '\%' or '%' to result as a percent
sign. Future versions may however support arguments and then '\%' will
oblige. The characters following the backslash are not case sensitive. By now
the following controls are supported.
`\\` displays the backslash itself
`\0` is compiled to a null character; ASCII code 0.
`\b` is compiled to the backspace character.
`\d` must be followed by exactly three decimal digits. If you've got less,
place leading zeroes. The sequence will be compiled to the ASCII code
represented by the decimal number.
`\f` is compiled to the formfeed character. This will feed the current page
out of a printer or on most systems clear the screen.
`\n` is compiled to a linefeed character. On most systems this will not only
feed, but also cause a carriage return.
`\r` is compiled to a carriage return character.
`\t` is compiled to a horizontal tabulator character.
`\v` is compiled to a vertical tabulator character.
`\x` must be followed by exactly two hexadecimal digits. If you've got only
one, place a leading zero. The sequence will be compiled to the ASCII code
represented by the hexadecimal number.
`\` must be followed by exactly three octal digits. If you've got less,
place leading zeroes. The sequence will be compiled to the ASCII code
represented by the octal number. Note that there is `no` extra identifier
behind the backslash.
3 dump
This terminal is used to auto-generate `include` files for DataProc itself.
It does not do any data formatting, but the result may be read in right
away even by the same commandfile e.g. after resetting the current table.
The `dump` terminal takes care that information about void data or misresults
won't get lost. It may also preserve titles and enviroment variables including
preambles.
4 enviroments
The very few supported enviroments for `dump` are:
`Global` will issue a #globtitle command to the destination to preserve the
current table name.
`NoSlip` switches off the generation of #slip commands to mark misresults.
`NoTitle` switches off the generation of titelling commands. Default is to
issue #title, #gtitle and #unit. Note that you will get misassigned titles,
if you change the column sequence or start by using when rereading the
table.
`Seps` sets the data separator character. Usually a space is used, but you
may feel like specifying other seperators either to generate output for
other programs or to get along with string type columns, which are by now
not quoted. That will change in future. Note that backslash controls are
supported.
`TermScan` scans the terminals for their enviroment settings and issues a
command sequence that sets those variables again when reread. Rereading
won't however cancel variables that have not been scanned, but set later
by your commandfile.
3 gnuplot
The primary data file holds the data to plot. The secondary file will have
a sequence of GNUPLOT commands written to. All you will still have to do
is to start GNUPLOT, type 'load "secondary file"' and you should see your
graphics on screen.
The `gnuplot` terminal writes no more than 4 data columns. The first column
is expected to hold the x-data and the second the y-data. If three columns
are given the third is interpreted as y-delta error and the errorbars style
is automatically written to the commandfile.
If 4 data columns are selected, you will need the inofficial GNUPLOT 3.1 that
was patched by me. This one supports an errorsquares style meaning x and y
errorbars. As this is an inofficial feature the terminal output will change
as soon as an official GNUPLOT supports x errors. Anyhow, the third column
holds the x errors and the fourth the y errors. The errorsquares style will
of course be automatically selected.
Void data is not plotted, but misresults are plotted plain without any
further marks. Future versions may enable you to switch that off.
If an `rtitle` is specified for the y-column and a regression had been done
to it, the regression graph is printed as well. Logarithmic regressions (See
`commands logreg`) are considered and printed correctly, so that you will
expect an arced graph in a linear scaled diagram. This graph is titled with
the `rtitle` string. All regressins are memorized!
The `globtitle` is set to GNUPLOT's equivalent. The column titles (See
`commands title`) are used to title the axes and their units are put in
square brackets. Finally the y-columns `gtitle` is used to label the
data plot.
Preambles (see `commands preamble`) are made exactly the first line of the
GNUPLOT commandfile. You may use them to custom scale the diagram, select
an output file for GNUPLOT and its terminal for instance. You will also
find it useful to tell GNUPLOT about scaling the axes e.g. by
#preamble "set logscale x"
Grouping is not supported. But you may merge columns (see `commands merge`)
and get multiple y-data and even regressions printed to the same x-axis.
Note that the terminal checks, if the x-axes of the various regressions are
compatible.
4 enviroment
Well, there is quite a lot of them for this terminal. You should be able to
produce any 2-D-plot you like. In the following I will use the Dollar symbol
'$' to indicate the variable's contents. In any case consult your GNUPLOT
manual. Here they are in detail:
`Angles` issues a "set angles $" to the commandfile. This is needed to switch
between radians and degrees in `polar` plots.
`AddPlot` contents are added behind a seperating comma behind the `plot`
command in the command file. This enables you to e.g. plot a theoretical
curve into your experimental data.
`Errorbars` forces a 4 column output to be handled with `errorbars` and not
`errorsquares`. This should always be set by users, who do not work with my
modified GNUPLOT, unless `errorsquares` becomes GNUPLOT standard in future.
`FullRange` contents will be verbally inserted at the position of ranges in
the GNUPlot command file. Note that you have to write the square brackets!
`Key` issues a "set key $" to the commandfile. This is needed to place the
graphics key in the plot, thus to get it out of interesting regions.
`Logscale` issues "set nologscale" if it is left empty. In any other case
it issues "set logscale $". You may want to use it with `logreg` plots.
`Output` issues a 'set output "$"' to the commandfile. You should use it as
soon you are sure the plot fits your needs. It saves a lot of typing.
`Polar` issues a "set polar" if set. By default "set nopolar" is issued.
`Range` issues a range after the `plot` command. The brackets are generated,
so you will only set the pure range stuff. Example:
#set range 1:8
will issue:
plot [1:8] ...
to the GNUPLOT commandfile. As you see you can only set the x-range by now,
but if you wish, I may add a more common enviroment variable.
`Size` issues a "set size $" to the commandfile. You will usually use it
together with `output` and `term`.
`Style` adds another data file plot to the `plot` command in the commandfile,
using the style given in the variable's contents. For Example:
#set style csplines
#ocol 1 2
#write "data.dat" "data.gnu"
would issue the following `plot` command to "data.gnu":
plot "data.dat", "data.dat" with csplines
Note that the `csplines` style -- data interpolation by cubic splines -- is
also a feature that doesn't come with the standard GNUPLOT, at least not by
now (GNUPLOT 3.2). But e.g. `lines` would be applicable with standard
GNUPLOT.
`term` issues a "set terminal $" to the commandfile. You will usually use that
together with `output`.
`tex` adapts the output for TeX style GNUPLOT terminals for a better TeX
graph formatting. You should always set this, if you intend to use the
GNUPLOT terminals 'latex', 'pictex', 'epic' or 'eepic'.
`yrange` works just like `range` but produces a range entry that affects the
y-range only. Note that `fullrange` overrides `yrange` which in tur overrides
`range`.
3 latex
The traditional terminal and meanwhile the most complex. At first a crude
overview. The latex terminal produces a LaTeX tabular enviroment for output.
This is written to the primary output file. The secondary output is ignored.
The whole table is put into an \fbox{}. The `globtitle` is set as a
\multicolumn{} stretching across the full table width. If it is missing, the
field won't be generated. Then group titles are displayed (see `commands
name`). If two or more columns of the same group are neighboured in their
logical write numbers, no vertical seperators will be drawn between them and
the group title will center in that \multicolumn{}.
The table's head is concluded by the column `title` and `unit`, which are
printed `title` over `unit` and each column separated by a vertical bar from
each other. If no units at all are specified the unit line will be
suppressed. The head is separated by a double horizontal bar from the table
itself.
Void entries are printed as '--' medium sized horizontal bars. Misresults
are printed in italics. The numbers are formatted and rounded as to the
precision selected in the `commandfile` (see `commands prec` and `commands
digital`). All entries are centered. Columns and rows are seperated by
vertical and horizontal bars.
After the table has concluded, the terminal scans for regressions, averages
and so on. If an averaging column or a regression's y-column is included in
the logical write list, all averaging and regression done to each of those
will be summarized and the results will be posted in new \tabular enviroments
following the main table. Future Versions may have a feature to influence its
style or switch it off.
Regression results are printed as y-title regression type superscript and
x-title. The superscript by now is German. The release Version will be
freely configurable. Then the A and B values are printed with errors and
units. The A unit is built by \frac{y-unit}{x-unit}. If the regressions were
logarithmic, \log is set before the corresponding unit.
Avaraging results are printed in a similar manner. Column title, superscript
(German by now, will be freely configurable) in the first line. The next
line holds \bar{x} the mean, its error and unit. The last line displys the
standard deviation with unit after \sigma. The whole thing displays a \pm
too much (after the standard deviation) by now, but I'll fix that until the
release version.
Finally results of 'far differences' made by `commands diff`. Just as
averaging results, but as no standard deviation is computed there is no
third line. The mean difference is named \bar{\triangle x}.
4 enviroment
The LaTeX terminal supports a whole lot of enviroment variables and is very
freely configurable. Beyond that I am sure that there will still be need for
further configuration variables.
The variable `RegData`, `Mean`, `MeanID`, `Diff` and `DiffID` serve to adapt
automessages to your native language. Other than in the old versions (1.120
and below) the default values are now English. I recommend to write an
`include` file for language adaption.
Except for the preamble backslash controls seemed not to be necessary and
thus are not supported by this terminal.
Here are the enviroment variables in detail. As before I use the Dollar symbol
'$' to indicate the variable contents.
`aID` sets the identifier string that preceeds regression slopes. Defaults
to "a".
`bID` sets the identifier string that preceeds regression offsets. Defaults
to "b".
`Caption` produces a \caption line. You will probably use it together with
`FloatHead`. The `globtitle` is used as caption and won't be issued anymore
in the table itself, when `caption` is set. If `caption` holds contents they
are used as the \label name. Example:
#globtitle Tabelle
#set caption mytab
would produce an output like:
\caption{\label{mytab} Tabelle}
`Corr` enables the output of correlation ratios in regression data blocks.
`CorrID` sets the identifier string that preceeds correlation ratios. Defaults
to $r$.
`Diff` sets the default name for "Differencing data", which is posted at the
beginning of a block containing those data.
`DiffID` sets a symbol for the differencing data, which is displayed directly
in front of the numerical value. This string defaults to $\bar{\triangle{x}}$.
`FloatHead` puts the whole table into a `table` and `center` enviroment as
most of you will probably do anyway. Well, it saves typing.
`Mean` sets the default name for "Averaging data", which is posted at the
beginning of a block containing those data.
`MeanID` sets a symbol for the averaging data, which is displayed directly
in front of the numerical value. This string defaults to $\bar{x}$.
`NoHead` inhibits the standard `tabular` header and titeling. Note that it
does not influence `caption` or `floathead`.
`NoReg` inhibits the regression data blocks which are printed following to
the table itself.
`RegData` sets the default name for "Regression data", which is posted at the
beginning of a block containing those data.
`Size` puts the table -- not the regression data blocks -- into a LaTeX
enviroment, which receives the name of the variable's contents. You may use
it for oversized (too wide) tables and select a smaller font for it. For
Example:
#set size scriptsize
would result in the structure:
optional FloatHead and Caption
\begin{scriptsize}
the table itself ...
\end{scriptsize}
regression data blocks ...
optional FloatHead close
`SuperTab` tells DataProc to use the supertabular enviroment. Note that you
need the corresponding style file to use this enviroment. As supertabular
can pagebreak in tables I recommend to use this option for long tables. Note
also that I cannot place the table into an enclosing \fbox anymore and thus
it looks a bit different, say more loosely, so for smaller tables you may
prefer the normal tabular still. `SuperTab` inhibits `NoHead`, but that my
change, if you request me to do it.
3 plain
This terminal was designed for a 7 bit ASCII output e.g. to a printer. You
may in some respects however select an extended charset and I'm working on
improving that. Beyond that I plan to write a terminal supporting graphics
facilities of printers.
The output format is similar to the `LaTeX` terminal. Please refer to that
section for detailed information about how the table and regression blocks
look like. As TeX does, all scaling is done automatically.
Note that other than the LaTeX terminal, plain supports backslash controls.
Backslash controls may be specified for any single character definition and
the `slip` style initer string. Of course like all the other terminals plain
supports those controls in its preamble.
4 enviroment
The enviroment variables differ a little from the `LaTeX` terminal and beyond
that there are many more of them to customize your output. Indeed I would
recommend an `include` file for your favorit settings. It may be a good idea
to select your screen as output file for table previewing and thus have an
`include` for your terminal as well. Now the enviroments in detail:
`aID` sets the string preceeding regression slopes in the regression data
summaries
`bID` sets the string preceeding regression offsets in the regression data
summaries
`Corr` enables output of the correlation ratio in the regression summaries.
`CorrID` sets the string to preceed correlation ratios. Defaults to r.
`Cross` the first character of the contents defines the character to use for
a single horizontal bar crossing a single vertical. Defaults to '+'. On
MS-DOS systems you may try: #set cross \d197
`Custom` allows you to custom scale the column widths of the table. The
variable string is parsed for `tokens`. Each of those tokens is parsed
for "number$width". This will set the fixed "width" to the table's
"number" column. Note that `spacing` is added left and right to the
column width, as well as one character for a vertical bar.
`Deviation` sets the string to issue in the regression blocks in front of
the standard deviation result, which is by now only supported by blocks
generated by `average`. Defaults to "Deviation".
`Diff` sets the string to issue in the regression blocks for titelling
data created by `diff`. Defaults to "Difference avaraging data".
`DiffID` sets the string to issue in front of the `diff` result. Defaults
to "Mean difference".
`Feed` sets the number of blank lines in front of the table. Defaults to
zero.
`HdCross` sets the character used for a single vertical bar crossing a
double horizontal. Defaults to '|'. On MS-DOS systems you may try:
#set hdcross \d216.
`HdLine` sets the character to use for a double horizontal bar. Defaults
to '='. On MS-DOS systems you may try: #set hdline \d205
`HLine` sets the character to use for a single horizontal bar. Defaults
to '-'. On MS-DOS systems you may try: #set hline \d196
`InterFeed` issues a formfeed between the table and the regression block
if set.
`Margin` sets the number of spaces left of the table and regression blocks.
Defaults to zero.
`Mean` sets the string to issue in the regression blocks for titelling
data created by `average`. Defaults to "Avaraging data".
`MeanID` sets the string to issue in front of the `average` result. Defaults
to "Mean".
`NoReg` suppresses the output of regression blocks if set.
`NoTable` suppresses the output of the table if set.
`RegData` sets the string to issue in the regression blocks for titelling
data created by `lreg` and `logreg`. Defaults to "Regression data".
`Slip` allows to define a control sequece to mark misresults. The variable
string is parsed as two `tokens`. The first one switches the slip style on,
the second off. The string is parsed as a C-type printf() format string.
Thus you may use e.g. "\x08" to define the ASCII control character number 8.
As you probably know "\x" introduces a hex number, the backslash alone an
octal number. You must write "\\" for the backslash itself and "\%" for a
%-sign. Each of both control strings may not exceed 29 characters. The
default is nothing.
`Small` tells the terminal to omit the single horizontal bars. This lets the
table appear more compact and reduces it to half its length. Try it out.
`Spacing` sets the number of spaces to place left and right of a table entry.
Defaults to one.
`VLine` sets the character to use for a single vertical bar. Defaults to '|'.
On MS-DOS systems #set vline \d179 is preferable.
2 errors
Well, I'm not very pleased with the error handling of neither DataProc itself
nor the math processor. The messages of latter are well defined and need no
further explanation, but the position marked, where the error should have
occured, is almost arbitrary. I will think of a better error handler when I
rewrite the math module.
The error messages of DataProc itself are typical for compilers. They are not
too definite and are usually caused by faults lines ahead. I will try to get
the whole stuff a little more transparent in future versions. At least I will
cite the errorline and command.
But here are the massages and what they mean:
Never mind -- it's a joke: well, ignore it and give me a note, if that
occures. The problem is a software bug.
Invalid column: the column number given is out of range. In
most cases you will have forgotten to define
the column (see `commands columns`)
Unknown command: tells you that the `command` is unknown. You
will supposedly have mispelled it.
Invalid function: the function number given was never defined
$ -> File "$" does not
open: the named file cannot be opened, because of the
numbered operating system error.
Invalid terminal: the named terminal is not found in the terminal
list. You will probably have mispelled it.
Low memory space: well, buy some RAM to cope with that.
Invalid mathematical
expression: should be followed by the message produced by
the math processor. See my words above of how
I think about those.
Invalid format descriptor: e.g. in `columns` you specified a column format
other than %d, %f, %lf, %s
No data for regression: In most cases that will mean that the y-column
or the wheigt columns are invalid. If they are
O.K. check your memory and if that isn't low
report it to me, because that may be a bug.
This of course applies to `average` and `diff`
as well.
Invalid group: the group number given was never defined. Define
the group or correct the number.
This should not appear: well, it's exactly that. There is certainly a
software bug.
Did not expect data here: should never appear. If so, give me a note.
Cannot add number tag: a global constant cannot be set, because either
the variable already exists or there is no memory
available to store it.
Unknown number tag: a number was represented by an unknown global
constant
Global constant expected: in a #define statement (or similar) an obligatory
name of a global variable is missing
Terminal enviroment
variable expected: in a #set or #unset command the variable key is
missing
Terminal enviroment
variable not parseable: you will have mispelled backslash controls in an
enviroment or preamble. Not that the error is
issued by the terminal and thus won't appear
when the definition was made.
Table size exceeded,
enlarge #dsize: should no longer appear
Column already exists: The column you want to add with #addcol is already
part of the table
Global string $ is not
parsable: The named global string cannot be evaluated. Check
your backslash syntax
The string $ is too long: A given string is longer than the field it should
be written to.
DOS command "$" failed: The command you passed to #dos caused an error
during execution
No more #IF opened: You called #else or #endif, but you did not
specify a corresponding #if.
#IF at line $ is not
closed: You exit a commandfile with an #IF command that
was not terminated by #ENDIF
Identifier expected: The command assigns a value to some symbolic
constant, but its name is missing.
Obligeous argument
missing: An argument that must be supplied is missing. Only
very few functions generate this error. By now it
is only #meanof and #wmeanof
$ writing file "$": the numbered operation system error occured during
output to the named file.
$ clearing file "$": the numbered operation system error occured when
flushing the buffers of the named file.
$ closing file "$": the numbered operation system error occured when
closing the named file.
$ working on file "$": the numbered operation system error occured during
non-I/O operations in the named file.
2 History
Some words on history. The internals of DataProc have been severly tested
during my physics practice and should work fine, but without any kind of
user friendliness. That were the revisions 1.0 to approximately 1.100. The
rest was spent on more abstract commandfiles and more flexible terminals
resulting in such as global variables, terminal enviroments and the removal
of case sensitivity. Performance has increased a little as well, although
I did not really optimize anything by now. The first version fulfilling
(hopefully!) this manual is 1.144. As the manual developed from 1.120 there
might still be some ancient remarks in it. Ignore them, if you find more
comfortable remarks somewhere else in this manual.
I added the `areg` command in revision 1.145, but as I already feared, the
math processor is much too instable and too slow for it. I tried to fit the
results of a slit experiment to a sinc-function. Using the same data in a
hardcoded program with the same subroutine worked fine, but the results of
DataProc are unusable and seem to be slightly divergent. So be very careful
using the `areg` command. This will -- has to -- improve with the new maths
processor.
SAS/C (tm) V6.0 arrived and I recompiled the old stuff. According to new
compiler warnings I found some errors in the code. Also I removed some bugs
in the `plain` terminal and made the `GNUPLOT` terminal useable without
TeX. I fitted the code for compilation on an IBM PC, detecting another set
of buggy code sequences. Finally I ran the standard Amiga test, meaning
MungWall and Enforcer and removed DataProc's Enforcer hits. Revision 1.153
is the product of all those internal bugfixes. DataProc became about 7 kB
longer but considerably faster.
Well, the first release should be DataProc 2.0, but I lacked of testers and
as it all works fine so far, I don't think it to be a big fault to release
Version 1.153 already.
Version 1.154 fixed the end vbar of the unit title line of the `plain` terminal.
Version 1.156 is almost the same code -- apart from a fix of the sgn() function,
but as I gained confidence in the code I set the optimize flags for the compiler
and DataProc shrinked about 12 kB and increased a great deal in speed.
Version 1.157 now supplies the `AddPlot` enviroment variable in the `GNUPLOT`
terminal to add theoretical functions to experimental data.
Version 1.162 supplies the `global string` feature and a slightly enhanced
error report feature. The latter will be one of the major concerns in future.
Version 1.167 fixes the boundary bug. Previous versions needed the upper
boundary to be set one higher than told in this manual, namely the first
excluded row. This bug is now fixed.
Version 1.169 introduces the enviroment variable `small` in the `plain`
terminal and fixes a disgusting bug in the `digital` type formatting of
output. It still does not work how it should, but it at least should not
produce wrong results anymore. As soon as I'll find some time I'll rewrite
that routine to ultimately fix that problem.
Version 1.174 is the promised `digital` fix. The new code might be slightly
slower, because it now uses floating point maths, but it has a crucial
difference. It has a chance to work and the first tests seemed very
positive. Beyond that the new modules have been compiled with SAS/C 6.1
resulting in even more effective code.
Version 1.177 is the answer to the reported rounding problems. Why hadn't
such severe problems been reported before? The trimming routines are now
completely rewritten and should be stable by now. Anyhow, there might still
be special cases that I didn't consider, so check the new routines carefully.
The behaviour has changed a little. Selecting a precision of 4 cyphers will
always result in a display of 4 significant cyphers, even if the last ones
are zeroes! Rounding should do fine now.
Version 1.178 adds the `runit` command and some smaller enhancements in
configurability.
Version 1.182 supports the LaTeX `supertabular` enviroment for LaTeX style
tables.
Version 1.187 now computes correlation ratios for linear and logarithmic
regressions, can monitor them to stdout, set them to math variables and
of course output them to the relevant terminals. Finally I found an Amiga
specific bug in the stdout management. Here's to you, Tim, now your stdout
will be sorted, finally!
Version 1.189 is the answer to a set of guys using this software extensively
but don't even think of paying for it. Well, this version is equipped with
a keyfile. It runs perfectly without a keyfile, if you got strong nerves,
but a valid keyfile will switch off those nasty intermezzos!? Well, see and
enjoy!
Version 1.202 is nothing but the (almost) perfection of the shareware
reminders. You will notice, what it is, while using it. Never mind, pay!
Just coming back from porting DataProc to MS-DOS. Finally it seems to run
fine as I thought of carrying my test files with me. I fixed a possible
bug in the maths processor that the compiler complained about. The handling
of the Keyfile changed a bit, because fseek() doesn't seem to work how it
should. In the end the MS-DOS users are the lucky guys, cause the most
nasty shareware reminder during the execution does not work. Don't be too
happy, but sure that I'll fix that. Version 1.203 is nothing but the
recompiled port sources.
Version 1.205 no longer requires the number token in the `columns` command.
Beyond that a bug in `columns` had been fixed allowing you to omit the
`using` command from your scripts. By default `DataProc` will read all
columns in the given sequence now.
Version 1.213 now allows to read several columns later. See the command
`row` that has been added. Beyond that `quit` and `execute` are new and
prepare an interactive mode. Finally a bug in the plain terminal has been
fixed. Well, I had some severe crashes, but I couldn't track them down to
DataProc. Two hours of constant testing with Enforcer and MungWall didn't
produce any hit ... so I tend to blame it on some other task. Anyhow, if
you encounter crashes, report them immediately and tell me what other tasks
are running, libraries installed, etc.
Version 1.214 is the product of two sleepless nights of debugging and
the `internal` version now owns a 40kB sized cross debugger. I will now
go to sleep telling you ... there ain't no more crashes! Ahh, before I
forget to mention it, there had been a display format bug with void data
in the plain terminal, this had been fixed during the last two nights as
well.
Version 1.221 has the interactive mode added. See documentation for
special information.
Version 1.225 is a bugfix compendium. First a bug I most likely have
implemented myself in 1.213 that prohibited DataProc from making columns,
which have already been generated by #make, is fixed. Then a typo in the
GnuPlot terminal was also fixed. And finally an annoying and heavy bug
in logscaled regression is removed. Note that any results you got from
logarithmic actions like #logreg used the natural logarithm and NOT the
decadic as mentioned in the manual. By now this is fixed. Finally weighted
logarithmic actions had been pure nonsense, this is fixed as well.
Version 1.227 fixed another typo in the GnuPlot terminal. Logarithmic plots
should now be perfect.
Version 1.228 fixed the `polar` enviroment in the gnuplot terminal. It now
works as it should.
Version 1.233 is another contribution to user friendliness. First you may
specify undefined global variables as function numbers in the `func` command
which will then automatically initialized, second the `dsize` command is
far less critical than before. See the commands' section for details.
Version 1.234 added the `addcol` and `remcol` commands. For all practical
purposes they are obsolete, but you may think them as a contribution to
the beauty of commandfiles. As I lack of time I had no time to test the
routines, but for all thats logic `addcol` has to run and `remcol` at least
should do.
Version 1.235 is the recompile of the 1.234 MS-DOS port on the Amiga machine.
The sources are now assured to be identical.
Version 1.236 is the product of half an hour using the program myself. For
what do I have testers, if they don't even notice severe uncomfortabilities?
The GnuPlot terminal now supports a `yrange` enviroment. The LaTeX terminal's
regression slope and offset identifiers are now configurable. Titles may now
be fed with global strings. Finally you may now open a logfile to store
additional information you may need while while writing down your results.
Version 1.238 fixes a handful of bugs I found in the same half hour. As
nobody complained, I assume nobody uses the features added since 1.100.
Version 1.239 adds the precision feature to the `build` command's float
conversion.
Version 1.241 fixes a bug that came in with the titles taking global strings
and an old bug in `mark`. `mark` now really works as described in this manual,
but it returned a one too small number in older versions.
Version 1.246 adds the tagfile support and the `dos` command.
Version 1.247 adds the `if` clause and a lot of interactive stuff. See `ask`,
`else`, `endif`, `if`, `readvar` and `stop` for more information. Tagfile
support was enhanced by `tagdata`.
Version 1.249 adds the enhanced batch support commands `storeset`, `flushset`
and `flushvar`. The online statisic commands `meanof` and `wmeanof` and
finally the plain terminal, too, supports the `aID` and `bID` enviroments.
Version 1.254 has a lot of the keyfile and shareware reminder stuff with
a completely new concept rewritten. I hope it now works on MS-DOS machines.
Note that unregistered MS-DOS versions crashed on some systems.
Version 1.258 adds the `storekill`, `closetag` and `closelog` commands. It
also fixes some bugs in the terminal enviroment variable storing code. Now
`input` may be used as a synonym for `include`, because me and some other
TeX freaks messed them up constantly. Finally the error handlig using
include files returned the location of the uppermost `include` command. This
is fixed by now and the correct location will be displayed.
Version 1.260 now monitors all file I/O errors and traps them. So on Amiga
systems you should have to press nasty requesters only one time. Originally
I wanted to find a bug by tracking I/O activity, but the bug is still in
there. During the installation of the control routines I optimized file I/O
a little. It seems to me that output got faster even though anything is
checked by now. Beyond that two new commands are installed. See `batch` and
`nop` for documentation. See also the chapter `errors`, because a whole lot
has changed there.
Version 1.263 is the result of 10 hours of bug hunt and I finally caught it,
it came in with `flushset` and caused weired error messages.
Version 1.264 is the recompile of the MS-DOS port. Some smaller bugs in
the I/O error handling had been resolved. Beyond that the MS-DOS file
I/O has been completely revised. At least with MS-DOS Version 6 everything
works all right -- yes the keyfile stuff as well!
Report errors, suggestions and registrations to:
MGR, Asgard
Lars Hanke
Schlachthofstr. 67
4690 Herne 2
Federal republic Germany
FIDO: Lars Hanke 2:245/5802.22
UUCP: mgr@asgard.bo.open.de
Good luck with this program and happy computing!